<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::ActiveRecord::ErrorMapping</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/github.css" type="text/css" media="screen" />
<script src="../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Module</span>
            Hoodoo::ActiveRecord::ErrorMapping
        </h1>
        <ul class="files">
            <li><a href="../../../files/lib/hoodoo/active/active_record/error_mapping_rb.html">lib/hoodoo/active/active_record/error_mapping.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p><a href="Support.html">Support</a> mixin for models subclassed from <a
href="Base.html">ActiveRecord::Base</a> providing a mapping between <a
href="../ActiveRecord.html">ActiveRecord</a> validation errors and platform
errors via <a
href="../ErrorDescriptions.html">Hoodoo::ErrorDescriptions</a> and <a
href="../Errors.html">Hoodoo::Errors</a>. See individual module methods for
examples, along with:</p>
<ul><li>
<p><a
href="http://guides.rubyonrails.org/active_record_basics.html">guides.rubyonrails.org/active_record_basics.html</a></p>
</li></ul>

<p>The error handling mechanism this mixin provides is intentionally analogous
to that used for resource-to-resource calls through <a
href="../Client/AugmentedBase.html">Hoodoo::Client::AugmentedBase</a>.</p>

    </div>








    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>A</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-adds_errors_to-3F">adds_errors_to?</a>
              </li>
          </ul>
        </dd>
        <dt>P</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-platform_errors">platform_errors</a>
              </li>
          </ul>
        </dd>
    </dl>










    <!-- Methods -->
      <div class="sectiontitle">Instance Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-i-adds_errors_to-3F">
              <b>adds_errors_to?</b>( collection )
            <a href="../../../classes/Hoodoo/ActiveRecord/ErrorMapping.html#method-i-adds_errors_to-3F" name="method-i-adds_errors_to-3F" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Validates the model instance and adds mapped-to-platform errors to a given
<a href="../Errors.html">Hoodoo::Errors</a> instance, if any validation
errors occur. For <a href="../ActiveRecord.html">ActiveRecord</a>
validation documentation, see:</p>
<ul><li>
<p><a
href="http://guides.rubyonrails.org/active_record_validations.html">guides.rubyonrails.org/active_record_validations.html</a></p>
</li></ul>

<p>Returns <code>true</code> if any errors were added (model instance is
invalid) else <code>false</code> if everything is OK (model instance is
valid).</p>

<h2 id="method-i-adds_errors_to-3F-label-Mapping+ActiveRecord+errors+to+API+errors">Mapping <a href="../ActiveRecord.html">ActiveRecord</a> errors to API errors</h2>

<p>The method makes an idiomatic example for “check errors in the model, map
them to platform errors in my service&#39;s response and return the result”
very simple, at the expense of modifying the passed-in error collection
contents (mutating a parameter is a risky pattern).</p>

<p>Given this example model:</p>

<pre><code>class SomeModel &lt; ActiveRecord::Base
  include Hoodoo::ActiveRecord::ErrorMapping
  # ...
end
</code></pre>

<p>…then a service&#39;s create method could do something like:</p>

<pre><code>def create( context )

  # Validate inbound creation data by e.g. schema through the
  # presenter layer - Hoodoo::Presenters::Base and
  # Hoodoo::Presenters::Base - then...

  model         = SomeModel.new
  model.param_1 = &#39;something based on inbound creation data&#39;

  # Ideally use the Writer mixin for concurrency-safe saving,
  # but in this simple example we&#39;ll just use #save directly;
  # unhandled database exceptions might be thrown:

  model.save()

  # Now exit, adding mapped errors to the response, if there
  # were validation failures when attempting to save.

  return if model.adds_errors_to?( context.response.errors )

  # ...else set &#39;context.response&#39; data appropriately.

end
</code></pre>

<p>An alternative pattern which avoids mutating the input parameter uses the
potentially less efficient, but conceptually cleaner method <a
href="ErrorMapping.html#method-i-platform_errors">platform_errors</a>.
Using <a
href="ErrorMapping.html#method-i-adds_errors_to-3F">adds_errors_to?</a> as
per the above code is faster, but the above example&#39;s use of
<code>save</code>, as per its comments, does not fully handle some
concurrency edge cases.</p>

<p>To win on both fronts use Hoodoo::ActiveRecord::Writer:</p>

<pre><code>def create( context )

  model         = SomeModel.new
  model.param_1 = &#39;something based on inbound creation data&#39;

  unless model.persist_in( context ).equal?( :success )
    context.response.add_errors( model.platform_errors )
    return
  end

  # ...else set &#39;context.response&#39; data appropriately.

end
</code></pre>

<p>In this case, the less efficient <a
href="ErrorMapping.html#method-i-platform_errors">platform_errors</a> call
only happens when we know we are in an error recovery situation anyway, in
which case it isn&#39;t as important to operate in as efficient a manner as
possible - provided one assumes that the non-error path is the much more
common case!</p>

<h2 id="method-i-adds_errors_to-3F-label-Associations">Associations</h2>

<p>When a model has associations and nested attributes are accepted for those
associations, a validity query on an instance constructed with nested
attributes will cause <a href="../ActiveRecord.html">ActiveRecord</a> to
traverse all such attributes and aggregate specific errors on the parent
object. This is specifically different from
<code>validates_associated</code>, wherein associations constructed and
attached through any means are validated independently, with validation
errors independently added to those objects and the parent only gaining a
generic “foo is invalid” error.</p>

<p>In such cases, the error mapper will attempt to path-traverse the
error&#39;s column references to determine the association&#39;s column
type and produce a fully mapped error with a reference to the full path.
Service authors are encouraged to use this approach if associations are
involved, as it yields the most comprehensive mapped error collection.</p>

<p>In the example below, note how the Child model does not need to include <a
href="../../Hoodoo.html">Hoodoo</a> error mapping (though it can do so
harmlessly if it so wishes) because it is the Parent model that drives the
mapping of all the validations aggregated by <a
href="../ActiveRecord.html">ActiveRecord</a> into an instance of Parent due
to <code>accepts_nested_attributes_for</code>.</p>

<p>So, given this:</p>

<pre><code>def Parent &lt; ActiveRecord::Base
  include Hoodoo::ActiveRecord::ErrorMapping

  has_many :children
  accepts_nested_attributes_for :children
end

def Child &lt; ActiveRecord::Base
  belongs_to :parent

  # ...then add ActiveRecord validations - e.g.:

  validates :some_child_field, :length =&gt; { :maximum =&gt; 5 }
end</code></pre>

<p>…then if a Parent were to be constructed thus:</p>

<pre><code>parent = Parent.new( {
  &quot;parent_field_1&quot; = &quot;foo&quot;,
  &quot;parent_field_2&quot; = &quot;bar&quot;,
  &quot;children_attributes&quot; = [
    { &quot;some_child_field&quot; = &quot;child_1_foo&quot; },
    { &quot;some_child_field&quot; = &quot;child_2_foo&quot; },
    # ...
  ],
  # ...
} )</code></pre>

<p>…then <code>parent.adds_errors_to?( some_collection )</code> could lead to
<code>some_collection</code> containing errors such as:</p>

<pre><code>{
  &quot;code&quot;      =&gt; &quot;generic.invalid_string&quot;,
  &quot;message    =&gt; &quot;is too long (maximum is 5 characters)&quot;,
  &quot;reference&quot; =&gt; &quot;children.some_child_field&quot;
}</code></pre>
<dl class="rdoc-list note-list"><dt><code>collection</code>
<dd>
<p>A <a href="../Errors.html">Hoodoo::Errors</a> instance, typically obtained
from the <a href="../Services/Context.html">Hoodoo::Services::Context</a>
instance passed to a service implementation in calls like <a
href="../Services/Implementation.html#method-i-list">Hoodoo::Services::Implementation#list</a>
or <a
href="../Services/Implementation.html#method-i-show">Hoodoo::Services::Implementation#show</a>,
via <code>context.response.errors</code> (i.e. <a
href="../Services/Context.html#attribute-i-response">Hoodoo::Services::Context#response</a>
/ <a
href="../Services/Response.html#attribute-i-errors">Hoodoo::Services::Response#errors</a>).
The collection you pass is updated if there are any errors recorded in the
model, by adding equivalent structured errors to the collection.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-adds_errors_to-3F_source')" id="l_method-i-adds_errors_to-3F_source">show</a>
              </p>
              <div id="method-i-adds_errors_to-3F_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/error_mapping.rb, line 185</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">adds_errors_to?</span>( <span class="ruby-identifier">collection</span> )

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">validate</span>()

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">errors</span>.<span class="ruby-identifier">messages</span>.<span class="ruby-identifier">each_pair</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">attribute_name</span>, <span class="ruby-identifier">message_array</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">attribute_name</span> = <span class="ruby-identifier">attribute_name</span>.<span class="ruby-identifier">to_s</span>

    <span class="ruby-identifier">attribute_type</span> = <span class="ruby-identifier">nz_co_loyalty_determine_deep_attribute_type</span>( <span class="ruby-identifier">attribute_name</span> )
    <span class="ruby-identifier">attribute_name</span> = <span class="ruby-string">&#39;model instance&#39;</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">attribute_name</span> <span class="ruby-operator">==</span> <span class="ruby-string">&#39;base&#39;</span>

    <span class="ruby-identifier">message_array</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">message</span> <span class="ruby-operator">|</span>
      <span class="ruby-identifier">error_code</span> = <span class="ruby-keyword">case</span> <span class="ruby-identifier">message</span>
        <span class="ruby-keyword">when</span> <span class="ruby-string">&#39;has already been taken&#39;</span>
          <span class="ruby-string">&#39;generic.invalid_duplication&#39;</span>
        <span class="ruby-keyword">else</span>
          <span class="ruby-identifier">attribute_type</span> <span class="ruby-operator">==</span> <span class="ruby-string">&#39;text&#39;</span> <span class="ruby-operator">?</span> <span class="ruby-string">&#39;generic.invalid_string&#39;</span> <span class="ruby-operator">:</span> <span class="ruby-node">&quot;generic.invalid_#{ attribute_type }&quot;</span>
      <span class="ruby-keyword">end</span>

      <span class="ruby-keyword">unless</span> <span class="ruby-identifier">collection</span>.<span class="ruby-identifier">descriptions</span>.<span class="ruby-identifier">recognised?</span>( <span class="ruby-identifier">error_code</span> )
        <span class="ruby-identifier">error_code</span> = <span class="ruby-string">&#39;generic.invalid_parameters&#39;</span>
      <span class="ruby-keyword">end</span>

      <span class="ruby-identifier">collection</span>.<span class="ruby-identifier">add_error</span>(
        <span class="ruby-identifier">error_code</span>,
        <span class="ruby-value">:message</span>   =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">message</span>,
        <span class="ruby-value">:reference</span> =<span class="ruby-operator">&gt;</span> { <span class="ruby-value">:field_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">attribute_name</span> }
      )
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">errors</span>.<span class="ruby-identifier">any?</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-platform_errors">
              <b>platform_errors</b>()
            <a href="../../../classes/Hoodoo/ActiveRecord/ErrorMapping.html#method-i-platform_errors" name="method-i-platform_errors" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Validate the model instance and return a <a
href="../Errors.html">Hoodoo::Errors</a> instance which contains no
platform errors if there are no model validation errors, else
mapped-to-platform errors if validation errors are encountered. For <a
href="../ActiveRecord.html">ActiveRecord</a> validation documentation, see:</p>
<ul><li>
<p><a
href="http://guides.rubyonrails.org/active_record_validations.html">guides.rubyonrails.org/active_record_validations.html</a></p>
</li></ul>

<p>This mixin method provides support for an alternative coding style to
method <a
href="ErrorMapping.html#method-i-adds_errors_to-3F">adds_errors_to?</a>, by
generating an <a href="../Errors.html">Errors</a> collection internally
rather than modifying one passed by the caller. It is less efficient than
calling <a
href="ErrorMapping.html#method-i-adds_errors_to-3F">adds_errors_to?</a> if
you have an existing errors collection already constructed, but otherwise
follows a cleaner design pattern.</p>

<p>See <a
href="ErrorMapping.html#method-i-adds_errors_to-3F">adds_errors_to?</a>
examples first, then compare the idiom shown there:</p>

<pre><code>return if model.adds_errors_to?( context.response.errors )
</code></pre>

<p>…with the idiomatic use of this method:</p>

<pre><code>context.response.add_errors( model.platform_errors )
return if context.response.halt_processing?
</code></pre>

<p>It is a little more verbose and in this example will run a little slower
due to the construction of the internal <a
href="../Errors.html">Hoodoo::Errors</a> instance followed by the addition
to the <code>context.response</code> collection, but you may prefer the
conceptually cleaner approach. You can lean on the return value of
add_errors and end up back at one line of (very slightly less obvious)
code, too:</p>

<pre><code>return if context.response.add_errors( model.platform_errors )
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-platform_errors_source')" id="l_method-i-platform_errors_source">show</a>
              </p>
              <div id="method-i-platform_errors_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/error_mapping.rb, line 250</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">platform_errors</span>
  <span class="ruby-identifier">collection</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Errors</span>.<span class="ruby-identifier">new</span>
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">adds_errors_to?</span>( <span class="ruby-identifier">collection</span> )

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">collection</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
